Amiga Format CD 24/Amiga Format AFCD24 (Feb 1998, Issue 108).iso/-in_the_mag-/emulation/uae/uae-0.4.3/readme

Text File | 1998-01-20 | 25KB | 507 lines

This is version 0.4.3 of UAE, the Un*x Amiga Emulator.

1. <drivel.h>

Copyright 1995, 1996 Bernd Schmidt & contributors (see below). This program is
freeware.  You may do whatever you want with it for personal use. Permission
is granted to call it a simulator if it makes you happy and you can give me a
satisfactory explanation why "simulator" and "emulator" are not synonyms.
Permission is granted to redistribute this program free of charge, provided it
is distributed in the full archive with unmodified contents and no profit
beyond the price of the media on which it is distributed is made. Exception: It
may be included on freeware/shareware collections on CD-ROM.
There are no warranties of any kind for this program. If you use this program,
you do so at your own risk. The authors are not responsible for any damages
that might result from using this program.
This program is still in an early development stage. It contains bugs and is
not user-friendly.

2. What you need to get it to work

  - a Un*x system with the X Window System, or, if you use Linux, SVGAlib.
    X is much more stable and not that much slower, so use X if possible.
    SVGAlib can get your system into an unusable state if it crashes. You
    have been warned.
  - A graphics card that lets you use a resolution of at least 800x600 in
    65536 colors. You can compile UAE for 256 color screens, but the colors
    will not be quite as good.
  - a C compiler. An _ANSI_ C compiler. What most workstation vendors ship
    is not a compiler, but a nightmare. Use GCC if it is available.
  - A Kickstart ROM file. I've heard success reports with Kickstart 1.3, 2.0,
    3.0 and 3.1 from various people.
    There seem to exist special 68020+ versions of newer Kickstarts. These
    will not work, neither will EPROM versions, and neither will ZKick files.
    Please do not ask me to send you one. The Kickstart is copyrighted, and I
    can't pass it around.
    This version of the emulator can boot some programs even without a
    Kickstart. See below for more information.

I've successfully tested UAE on the following systems:
  - Pentium-90, Linux 1.3.45; X11R6 (XFree86 3.1.1) / SVGAlib 1.2.9, GCC 2.7.2
  - HP Apollo, HP-UX, X11R5, GCC 2.6.0
  - Sun Sparcstation, Solaris, OpenWindows, GCC 2.6.1

Several people have successfully run previous versions on a variety of
systems, including a SGI Indy, Suns, a DEC Alpha and a m88k based Unix box.

3. Installation

Please note: I know that the installation procedure could be improved. I
always hate it if I have to change the Makefile or header files to install a
program. But this is the best I could come up with so far.

To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae
on a Linux system). After that, you will have to edit the file config.h. There
are many configuration options, each with a comment describing the purpose.
Please read everything carefully.
Unlike in previous versions, you should not need to edit the Makefile.
However, if X11 is installed in a different place on your system, you might
need to change the "/usr/X11R6/" bits to "/usr/X11R5" or whatever is
appropriate.
The Makefile knows about a variety of systems. Do "make linux" to compile for
the X Window System under Linux. Do "make svga" to use SVGAlib. There are
several other systems: Do just "make" to get a list. If nothing else works,
try "make withgcc", and if that does not work because GCC is not installed,
"make generic". When that fails, send me an email.
If you use SVGAlib, be warned that SVGAlib is not too stable and using it is
inherently a little dangerous, you might want to have a way to log in from a
remote terminal if things go horribly wrong. If you are very unfortunate, you
might lock up your machine otherwise (I strongly recommend using X - it is
no longer much slower).

There is an experimental user-interface for X in this version. Currently, you
have to make a decision whether you want to try it or not. You can try it by
saying "make linux-gui" instead of "make linux" (users of other systems will
have to edit the Makefile by hand, sorry). This requires that you have
tcl7.4 and tk4.0 installed on your system.

The compilation may take a while, especially for the cpu*.c files. There might
be some warnings, ignore these. It may also take a lot of memory. You should
have at least 8MB physical RAM to compile this, plus maybe 20MB swap and 9MB
filesystem space.

After compilation, you'll need to install the ROM image. This must have a size
of exactly 512K and should be an image of the addresses 0xF80000-0xFFFFFF on
your Amiga system. The file must be called kick.rom to be recognized. Please
read the next section on how to transfer files from your Amiga to your PC.

You can also install a disk image file. This must be called df0.adf (adf =
Amiga Disk File), and should be a raw image of the data on the floppy disk:
11x2x80 sectors == 901120 bytes.
Please try running UAE without a diskfile first. If everything went O.K., the
emulator should show the Kickstart logo (don't be too impatient, this will
take a while on slow machines).

If you don't have a Kickstart file, you may still be able to boot some games
and demos. The emulator includes code that will try to read and execute the
bootblock of the diskfile you are using, and if that bootblock only uses the
one or two Kickstart functions that are supported by the "replacement
Kickstart", your program will boot. Don't expect too much, though.

4. Invoking UAE

After building the program, you should have an executable called "uae". You
can simply execute it, but you can also optionally give it one of the following
parameters:

 -h      : Give help on the options.
 -d      : If UAE is not configured to use correct-aspect display by default,
           this option will enable it.
 -f rate : Sets the frame rate
 -D      : Don't start the emulator at once, use the built-in debugger.
 -x      : (X Windows only) Enable a slower, but more portable version of the
           drawing routines. If you need this switch, I'd like to hear about
       it (it seems unlikely).
 -l lang : Set the keyboard language at run-time. Currently, only two values
           can be used for lang: "us" for U.S. keyboard (default), or "de" for
       german keyboard.
 -s      : Emulate slow memory at 0xC00000. Some demos/games need this.
 -F      : Emulate fast memory as an expansion board.
 -S      : If you set the LINUX_SOUND option in config.h, you can turn off
           sound output with this switch.
 -M VOLUME:path
 -m VOLUME:path
           mount the unix file system at path as an Amiga filesystem with
       volume name "VOLUME:". For example, "-M sound:/usr/amiga/modules"
       If you use -M instead of -m, the volume will be read only.
       See below.

If you use SVGAlib, the only way to leave the program is pressing F12.

5. Harddisk emulation

Using diskfiles is awkward. There are two ways how you can use larger amounts
of data with UAE.

a) Harddisk files.
You can create a harddisk file with

  dd if=/dev/zero of=hardfile bs=512 count=16384

Currently, the size is fixed (8MB). This might be configurable in future
versions.
The harddisk file is accessed by a resident ROM module that is built into the
emulator. It's called "uae.device", the DOS name for the harddisk is "uae0:".
You have to format it before use (from AmigaDOS).

I don't think I will support this in the future. If I get no emails from users
protesting "I put all my files on it", I'll remove the code again, because you
can

b) Access unix filesystems from the emulator.

This has some major advantages:
 - It also works with Kickstart 1.3.
 - It is more convenient.
 - It is much faster. In fact, it can be dramatically faster even than a real
   Amiga when reading directories.

If you specify the -M or -m command line arguments, you can use files on your
Unix filesystem from the emulator. If you start UAE with

  uae -m sound:/usr/amiga/modules

you can access all the files in /usr/amiga/modules by reading from the
AmigaDOS volume "SOUND:".
If you want to execute files, they need to have the x permission bit set.

In theory, you can specify this option multiple times. In practice, this
doesn't work with Kickstart 1.3 and was therefore turned off. This will get
fixed, I hope.

6. Tools

In the "amiga" subdirectory you'll find two small tools that you can use to
transfer software from the Amiga to the PC. These are called transrom and
transdisk. transrom will dump the contents of your Kickstart ROM, and
transdisk will dump an image of the floppy in drive DF0:. Both programs write
to the standard output, so you want to redirect that. Do

   transrom >ram:kick.rom

to create a file called "kick.rom" in the RAM disk, and

   transdisk >ram:df0.adf

to create a file called "df0.adf" in the RAM disk. These files are pretty
big, 524288 bytes for the ROM image and 901120 bytes for a disk image. If you
are short on RAM (less than 1.5MB) you may want to transfer those files
directly to a serial link between the Amiga and your Un*x system (works
without a problem for me).
transdisk can take extra arguments: A device name and unit number. If you do

  transdisk >ram:df1.adf trackdisk 1

the program will read the data from drive 1, not drive 0.

The current transdisk can only read the standard AmigaDOS format. You will
not be able to transfer copy protected disks. Although the current emulator
version can handle a second type of disk file, and I have successfully
transferred and run a copy protected game (Turrican I) on the emulator, this
support is preliminary, and the disk file format for non-standard disk formats
will probably change in future versions. If you also have Turrican and want
the program I used to transfer the disk, mail me.

If you transfer commercial software, you must not distribute the resulting
image files, since that would be a violation of copyright law. The Kickstart
ROM has to be considered commercial software. You may only use the Kickstart
from your own Amiga, and you may not distribute Kickstart ROM files.
Please read the license that came with your software for details.

If you have a disk image file, and you want to retrieve the files from it, you
can use the "readdisk" tool. It is automatically built by "make". If you have
a disk image of a disk called "Workbench1.3D" as df0.adf, and you do
   readdisk df0.adf
the whole directory structure of the disk image will be stored in a newly
created subdirectory called "Workbench1.3D". You can optionally give a second
parameter to specify a directory where to create the output other than the
current directory.
readdisk only understands about the OFS right now. FFS disks will be
cheerfully regarded as being unreadable. Use the unixfs.device from within the
emulator if you want to transfer files from FFS disks.

7. Quick overview of the debugger commands

If you use the X Windows version, you can press ^C at any time to enter the
built-in MC68000 debugger.
Each debugger command consists of a single letter and occasionally some
parameters.

g:                    Start execution at the current address.
c:                    Dump state of the CIA and custom chips.
r:                    Dump state of the CPU
m <address> <lines>:  Memory dump starting at <address>
d <address> <lines>:  Disassembly starting at <address>
t:                    Step one instruction
z:                    Step through one instruction - useful for JSR, DBRA etc.
f <address>:          Step forward until PC == <address>
q:                    Quit the emulator. You don't want to use this command.

(^C has no effect if UAE is compiled for SVGAlib - use F12 to exit)

8. Current state of UAE

The following parts are already mostly complete:
  - MC68000 CPU: Almost done, some rare instructions are not emulated yet.
    I'd like to make this a 68020 emulation, but I need more info than I have
    about the special registers (MMU etc.)
    Maybe it will one day run Linux/68k!
  - Blitter: If there's no bug, it ought to be complete.
  - Timers: I think these are fully working, too.
  - Copper: Not much to emulate here :-)
  - Floppy disk: Standard AmigaDOS disks seem to work O.K., some special
    formats can be made to work (not yet really supported).
  - Playfield (display) hardware: Normal cases are working, as well as
    dual playfields, EHB and HAM and interlace (interlace only with correct
    aspect)
  - Mouse, Keyboard, Joystick: Mouse and joystick should be autocalibrating.
    Only DE and US are supported as keyboard languages.
  - Sprites: Still one or two bugs, but usually working.
  - Sound: Some support (Linux only). Not too useful right now. See below.

Not done:
  - "System control hardware": That's what the HRM calls sprite/playfield
    collisions/priorities. Only the most common priority settings are
    implemented.
  - Timing: It does not really behave like a real A500, but I don't think
    complete accuracy is necessary.

9. Input devices

Mouse, keyboard and joystick can be used in a straightforward way. Two
keyboard languages are supported right now: german and US keyboard. If you
have a different keyboard, patches to make UAE work with it are appreciated.
The X version of the emulator will try to keep the Amiga mouse pointer at the
same location as the X mouse pointer. You can turn off this mode if it does
not work with your program by pressing F12. This is needed (for example) for
Lemmings and the Magnetic Scrolls adventures, which don't use sprite 0 as a
mouse pointer. The SVGAlib version does not have this problem.
If you use Linux and have the joystick driver kernel module, you can configure
UAE to use it. The joystick should be autocalibrating. Turn it a few times on
startup to get the calibration done.

10. Sound

You probably noticed the LINUX_SOUND configuration option. If defined, this
will make the emulator use /dev/dsp to output sound with 16 bit, at a frequency
of 44100KHz. Your soundcard has to support this rate. If it does not, your
results will be unpredictable.
If graphics output is enabled while sound is output, the emulator will be much
too slow on all current systems. The sound will not be continuous. Therefore,
a hack to turn off screen updates is provided: Press ScrollLock to disable
graphics, press it again to enable them (note: for X, you'll have to press it
twice each time).
The LINUX_SOUND_SLOW_MACHINE option will steal cycles from the CPU emulator.
The relative CPU speed will be reduced somewhat if this option is set. This may
lead to incompatibilities. The system should not be heavily loaded (no blitter
or disk activity) while sound is being played, or even this will be too slow.
Only a subset of the Amiga sound hardware is emulated. Attached channels are
not implemented, neither is CPU-driven output.

Currently, this implementation is good enough to play *Tracker modules and
some game title melodies. It is fast enough (on a P90, without the
LINUX_SOUND_SLOW_MACHINE option) to play modules using a Workbench player
program if no other (Amiga) processes are active.

On other Unix systems, the AF sound system may be available. You can configure
UAE to use this, too, by changing some paths in the Makefile.

11. Speed

A Pentium with about 500MHz would be nice... (*)
but even a Pentium-90 is not that bad, if you set the frame rate to a high
value, e.g. 9. Animations will not be smooth if not all frames are drawn, but
the speed of the emulation will be considerably higher.
The speed of the emulation is not fixed. Programs that make heavy use of
blitter, copper and disk DMA will run somewhat slower than programs that only
use the CPU. More bitplanes and sprites will also slow things down. The speed
also depends very much on configuration options.
UAE can calculate the average time it needs to finish one Amiga frame. Use the
'c' debugging command. If you use SVGAlib, the average frame rate will be
displayed when you exit UAE, provided the library doesn't mess up your
text-mode screen when you exit.

There used to be a table here with speed comparisons, but it was getting
constantly out of date. Short summary: A Pentium-90 will be 4-5 times slower
than a real A500 at full frame  rate. If you reduce the frame rate, it is only
about 2 times slower. It can achieve full speed for sound output if graphics
are turned off (useful for module players).

(*) Try buying a 500MHz clock and a fire extinguisher :-)

12. Frequently Asked Questions, and Common Misunderstandings

Q: Will there be a Windows version?
A: I'll never write a non-commercial program for DOS/Windows again. I hate
   having to reboot after mistakes.
   I included the DOS port because a) a DOS version can achieve similar
   speeds as the Linux/SVGA version b) it didn't messify too much of the code,
   and c) more people told me they would port it to DOS and I wanted to save
   them the effort. I don't think a Windows port will fit in as cleanly as the
   DOS port, nor do I think it can be efficient. If you want, you can try to
   prove me wrong, but I will be very reluctant to include Windows code. The
   same goes for code to support a bazillion soundcards for DOS, or similar
   nightmares.

Q: I get lots of compilation errors. Why?
A: The most popular reason was a missing libg.sa in /usr/lib (Slackware bug).
   Do "cd /usr/lib; ln -s libc.sa libg.sa". That should no longer hurt with
   this version, though.
   Another possibility is that you botched your system in an ELF upgrade.
   Check whether GCC, binutils, libc, ld.so, X11 etc. are all uptodate and
   installed for the same binary format.
   Some people have been getting strange linker errors with 0.4.2 again...
   upgrade binutils and complain to the linux-gcc list.

Q: How can I change diskfiles?
A: Try using the linux-gui target when you build UAE. See above.

Q: Is it possible to read Amiga disks with a PC?
A: Ask that in comp.emulators.misc :-) The answer is: NO! Unless you invent
   and build some extra hardware yourself, which no one appears to have done
   yet.

Q: When it starts up, it says "Illegal instruction: 4e7b". Why?
A: That's normal, it's just the Kickstart CPU type test.

Q: When it starts up, it says "Illegal instruction: 00f8" (many times). Why?
A: That's because your Kickstart ROM was compiled for the 68020.

Q: While it compiles, it says "xxx illegals generated" or "16 mismatches".
   Is this a problem?
A: No. I can use this information to tell whether there is a problem, and
   there isn't.

Q: Why is there a blank area on the left side of the screen?
A: The Amiga can display graphics there, but usually doesn't because this
   would disable some sprites. The area is only used by some overscan demos.
   Normal screens are off-center. Please don't send me any more mail with "can
   you fix this one" subjects. The answer is: "Maybe. Aren't there any worse
   problems?".

Q: Benchmark program <foo> gives weird results.
A: Amiga programs run by the emulator think the Amiga timers can be used to
   measure real time. But in UAE, they only measure "emulation time". Sysinfo,
   for example, gives the same results on all machines. So don't run
   benchmarks to test the emulator speed.

Q: Wasn't this called the Unusable Amiga Emulator?
A: Yes. But no one thought the name was very fitting anymore, though. It was
   only really appropriate for v0.1, which couldn't even boot.

Q: Sometimes, after UAE exits, there is no autorepeat for the keys!
A: Do "xset r on" (happens only in X).

Q: Emulating all the hardware is a bad idea. Why don't you just emulate the
   OS? After all, that's what makes the Amiga the Amiga.
A: Short answer: I disagree.
   Long answer: The OS is half of what makes the Amiga the Amiga. It is a very
   nice OS, and there are some features that I miss in any other OS, but it is
   also severely lacking in terms of (for example) memory protection and
   filesystem performance.
   The other thing that made the Amiga special back in the 1980s is the custom
   chip architecture. If you look into old (1985) computer magazines, you will
   find that the capabilites of the Amiga OS are only mentioned as a side
   note, because people were not aware that it was revolutionary for a home
   computer. They were aware, though, that the Amiga could display 4096 colors
   at the same time and that it had a blitter and a copper that could do all
   sorts of stuff, like bouncing balls for instance. And I think it was the
   superiority of the hardware that made the Amiga a success.
   I see UAE as a program that is similar to C64 emulators: it allows you to
   run some old games and other programs that you can't replace with better
   equivalents on the PC. As such, it can already be used to run non-action
   games (like Monkey Island or Bard's Tale) at a satisfactory speed. Faster
   CPUs will eventually make it possible to run action games, just like faster
   CPUs have made it possible to emulate a C64 at full speed on a PC. UAE is
   not (primarily) meant for the Amiga PowerUser who is running high quality
   applications on his A4000 with a 68060 board, but for people like me who
   switched from an A500 to the PC a few years ago because they wanted to make
   money by developing software.
   Besides, emulating an OS is far more difficult IMHO. Especially if the
   platform you are emulating it on is completely different than the platform
   that is being emulated. You'd have to mess with endianness conversions and
   other nightmares. The AmigaOS wasn't designed with portability in mind
   either.

Q: How can I transfer non-DOS disks that are used by many demos?
A: With transdisk. The fact that they are unreadable by AmigaDOS does not
   mean they are unreadble by transdisk. Only copy-protected disks can't be
   transferred that way.

13. Thanks & Acknowledgements

Thanks to all who have written me so far with bugreports and success/failure
reports when trying to run the emulator on various hardware with different
Kickstart versions.

Special thanks (in no particular order) to:
  - Jay Miner, Dale Luck, R.J. Mical and all the others who built the Amiga.
  - Felix Bardos, whose HRM I "borrowed".
  - Hetz Ben Hamo mailed Peter Kittel from Commodore asking for permission to
    give Kick 1.3 away. Unfortunately, the response was negative :-(

  the contributors:
  - Alessandro Bissacco: X Windows mouse auto-calibration, battclock emulation
    and various bugfixes.
  - Hannu Rummukainen: Floppy write emulation.
  - Andre Beck: Made the X support much faster by using MIT-SHM extensions.
    (Not bad for a 10 minute hack, Andre!)
  - Ed Hanway: Wrote the unixfs.device. Improvements to the X support (cursor
    blanking, etc.), lots of SGI compatibility fixes, run time options. He
    also sent me a copy of his own (unfinished) Amiga emulator...
  - Ernesto Corvi: Mac port
  - Denis Sablic: Misc. bugfixes, "-S" runtime option.
  - Marcus Sundberg: Better transdisk, bugfixes, DEC Alpha diagnostics,
    support for the AF sound system found on some Unix boxes.
  - Samuel Devulder: LOW_BANDWIDTH option for X.
  - Stefan Reinauer: fixed battclock for KS >1.3, added AutoConfig/fastmem
    support.
  - Marco Nelissen: found bug in CIA code; copper & sprite bugfixes.
  - Thierry Lescot: Win95 keyboard support for SVGAlib.
  - Gustavo Goedert: DOS version
  - Bruno Coste: Better keyboard support for X
  - Thorsten Frueauf: NetBSD fixes.

Please let me know whether it's OK to include your email address here,
especially if you have made a large contribution that people may have
questions about.

14. Ports

Apart from the "main" Unix version, several ports of UAE are ready/being
developed.

Gustavo Goedert <[e-mail]> has ported UAE to DOS using the
DJGPP port of GCC. It is available on several ftp sites as well as on my Web
site.

Ernesto Corvi <[e-mail]> has ported UAE to the PPC-Mac.
I'm currently trying to figure out where he uploaded the binaries. When I'm
done with that, the Mac version will also become available on my Web page.

Since I generally don't have the possibility to test or improve these ports,
it is a good idea to contact their respective authors if you have questions.

15. The author's address

[e-mail]

or, via snailmail

Bernd Schmidt
Schlossweiherstrasse 14
52072 Aachen
Germany

I'll *try* to reply to everyone who sends me mail. Email has a near 100%
chance of being replied, although my mailbox has been overflowing recently.
Please read all of the manual, especially the FAQ section, before asking me
about problems.
I can't make any guarantees about snailmail.

I have set up a WEB page for UAE. You will find interim versions, Linux
binaries, diskfiles with Amiga software and other interesting stuff there.
The address is

http://www-users.informatik.rwth-aachen.de/~crux/uae.html